home *** CD-ROM | disk | FTP | other *** search
/ Shareware Grab Bag / Shareware Grab Bag.iso / 002 / bb645.arc / BBF.DOC < prev    next >
Text File  |  1987-02-09  |  10KB  |  329 lines
  1.                             ██████████
  2.               ██████████████      
  3.              ███ · ████ · ███
  4.               ██████████████
  5.               ██████  ██████
  6.                ████████████
  7.                  ████████
  8.                 ██││││││██
  9.                  ████████
  10.              ██▄          ▄██
  11.               ▀██▄      ▄██▀
  12.                 ▀██▄  ▄██▀
  13.                   ▀████▀
  14.                   ▄████▄
  15.                 ▄██▀  ▀██▄
  16.               ▄██▀      ▀██▄
  17.              ██▀          ▀██
  18.  
  19.               ┌────────────┐
  20.               │ BLACKBEARD │
  21.               └────────────┘
  22.  
  23.               User Supported Software
  24.  
  25.  
  26.                VERSION LOG
  27.               BLACKBEARD FORMATTER
  28.  
  29. version  remarks
  30. ------------------------------------------------------------------
  31. 1.0      First release version of the formatter.
  32.  
  33. 1.1      Added sections and table of contents feature and include
  34.      file.
  35.  
  36. 1.2      Multi-line titles (upto 10)
  37.  
  38. 1.3      Fixed bug that truncated first line to the length of the
  39.      title.
  40.  
  41. 1.4      File terminated with FF CR LF
  42.  
  43. 1.5      Title does not skip spaces when using multi-line titles.
  44.  
  45. 1.6      Require function added to allow merging of files.
  46.  
  47. 1.7      Bold function to insert special bold sequences
  48.  
  49. 2.0      New C Compiler used. Output command added.
  50.  
  51. 2.1      Bold start & end sequences added.
  52.  
  53. 2.2      Latest BB 6.45 distribution version.  2-9-87.
  54.  
  55.  
  56. INTRODUCTION
  57.  
  58.    Printing out documents is an essential associated task of a
  59. text processing system. Blackbeard performs the editing tasks
  60. very well. An available text formatter/printer was not
  61. available. Programs like Microsoft Word (R) are so word
  62. processing oriented that simplicity is often compromised. The
  63. Blackbeard formatter is a simple to use, do what I tell you, text
  64. processor.  It takes any text file and produce a cleaned up
  65. printed output.  It is also a powerful formatter for producing
  66. technical documents.  A design constraint was that the initial
  67. version be compatible with DEC's DSR (R) as much as possible.
  68.  
  69.    This manual describes how to use the formatter.
  70.  
  71. RUNNING BLACKBEARD FORMATTER
  72.  
  73.    To run Blackbeard formatter type:
  74.  
  75.       BBF
  76.  
  77.    or
  78.  
  79.       BBF {filename}
  80.  
  81.    BBF does not include a pop-up directory of files to format
  82. yet (available real soon now). BBF will then format your
  83. document and write it to the standard output device (the
  84. screen). To send the output to the printer run Blackbeard with
  85. the command:
  86.  
  87.       BBF {filename} >prn
  88.  
  89.    This redirects output to the printer. You could also
  90. redirect the output to a filename if you want by substituting a
  91. filename for prn.
  92.  
  93. The default format is to print 2 blank lines at the top of the
  94. page, the filename (used for the title), 2 more blank lines,
  95. text lines as they appear in the file (no formatting is done,
  96. except for tabs are converted to spaces, fonts are replaced if
  97. enabled and spaces are insert if a left margin is used), 2 blank
  98. lines, a page number, and a form feed.
  99.  
  100. COMMANDS
  101.  
  102.    The nature of the format can be altered by embedding
  103. formatter commands (often known as dot commands) in your text.
  104. The general format is:
  105.  
  106. .command parameter1 parameter2 text
  107.  
  108. The following is a description of the available commands.
  109.  
  110. .bold c string
  111.    Sets up a bold charater indicator.  When the bold
  112.    character is first encountered in the text, all subsequent
  113.    characters are duplicated and the string is inserted between
  114.    the duplicated characters until a terminating bold character
  115.    is encountered.  Example:
  116.  
  117.    .bold @ &a+
  118.    abc@def@ghi
  119.  
  120.    formats to:
  121.  
  122.    abcd&a+de&a+ef&a+fghi
  123.  
  124. .bs c string
  125. .be c string
  126.    Sets up a bold charater indicator.  When the bold character is
  127.    first encountered in the text, all subsequent characters are
  128.    duplicated and the string designated with .bs is inserted
  129.    between the duplicated characters and the string designated
  130.    with .be is inserted after the duplicated character until a
  131.    terminating bold character is encountered.  Example:
  132.  
  133. .bs  &a-67H
  134. .be  &a-5H
  135.  
  136. is the sequence to perform bolding on the HP Laserjet+ with the
  137. standard 10CPI font. For:
  138.  
  139.    XYZ
  140.  
  141.    the string:
  142.  
  143.    X&a-67HX&a-5HY&a-67HY&a-5HZ&a-67HZ&a-5H
  144.  
  145.    is produced.  The HP laserjet+ perform the following
  146. operations when receiving this sequence.  An X is printed then
  147. the jet is moved "horizontally backward" 67 decipoints (i.e.,
  148. just less than the character width of 72 decipoints), the
  149. character X is printed again, and the jet is moved "horizontally
  150. backward" 5 decipoints, which is the compensation for not having
  151. moved back 72 originally.  So the character appears bold having
  152. been printed once and the offset printed again.
  153.    This formatting command can cause your document to become
  154. uneditable since lines can get very long.  Essentially each
  155. bolded charater becomes equivalent to 15 characters (in this
  156. example).  So if you have a line of 20 bolded characters, that
  157. line is now 300 characters long! The max line length the
  158. Blackbeard formatter can currently accomodate is 4096
  159. characters.  So for this example that is a line of 273
  160. characters.
  161.  
  162. .dump string
  163.    Dumps a string to the file designated by the file command.
  164.  
  165. .enable c
  166.    Set the font character as the character c. For example:
  167.  
  168.    .enable 
  169.  
  170. .file filename
  171.    This command causes the formatter to place all header numbers
  172.    and titles in the specified file.  This functions as a table
  173.    of contents.
  174.  
  175. .fm before-title after-title before-footer after-footer
  176.    Specify the page layout:
  177.  
  178.   ┌─────────────────────────────────┐
  179.   │        before-title            │
  180.   │    Title line                   │
  181.   │       after-title              │
  182.   │    This is a sample text line.  │
  183.   │    This is a sample text line.  │
  184.   │<-> This is a sample text line.  │
  185.   │lm  This is a sample text line.  │
  186.   │    This is a sample text line.  │
  187.   │    This is a sample text line.  │
  188.   │    This is a sample text line.  │
  189.   │    This is a sample text line.  │
  190.   │    This is a sample text line.  │
  191.   │    This is a sample text line.  │
  192.   │    This is a sample text line.  │
  193.   │    This is a sample text line.  │
  194.   │       before-footer            │
  195.   │    Footer line                  │
  196.   │       after-footer             │
  197.   └─────────────────────────────────┘
  198.  
  199.   The number of blank spaces at the top and bottom of the text.
  200. Default is 2 2 2 2.
  201.  
  202. .fo
  203.    Running footer at the bottom of page.  A # represents the page
  204.    number.
  205.  
  206. .hl n
  207.    This is the header level command. It allows you to create
  208.    relocatable sections and produce automatic numbering like
  209.    1.2.4.6.
  210.  
  211.    Example:
  212.  
  213.    .hl 1 Section 1
  214.    .hl 2 Section 1.1
  215.    .hl 3 Section 1.1.1
  216.    .hl 2 Section 1.2
  217.    .hl 1 Section 2
  218.  
  219. .include filename
  220.    This will emplace a file -- as is -- in the file you are
  221.    currently formatting.  This command includes graphics as well
  222.    as ASCII files.
  223.  
  224. .le
  225.    This is a list element. It allows you to create a numbered
  226.    list.
  227.  
  228. .ls
  229.    List start. Starts (and ends) an itemized list.
  230.  
  231. .lm n
  232.    Left margin. Default is 0.
  233.  
  234. .nmlv header-level number
  235.    Reset header level numbering.
  236.  
  237. .nmpg n
  238.    Reset page number.
  239.  
  240. .output s
  241.    Outputs the string s without considering it as text. This can
  242.    be used to reset the printer, e.g., landscape to portrait
  243.    mode.
  244. .pg
  245.    New page.
  246.  
  247. .ps n
  248.    Page size with n in lines per page. Default is 66.
  249.  
  250. .req filename
  251.    This will emplace a file and reformat as required in the file
  252.    you are currently formatting.  This command can be nested, but
  253.    only ten files can be required at any one time.
  254.  
  255. .ti [n] text
  256.    Running title on top of page.  A # in the title text
  257.    represents the page number.  Multiple line titles can be
  258.    designated by preceding the title with a number between 0 and
  259.    9.  For example to get a two line title use the commands:
  260.  
  261.    .ti 0 First title line
  262.    .ti 1 Second title line
  263.  
  264.  
  265. FONTS
  266.  
  267.    The formatter can also perform font translation.  It does
  268. this by recognizing font designators in your text file.  A
  269. font designator begins with the ASCII font character such as
  270.  followed by another ASCII character for the font number
  271. such as  for the first font.
  272.  
  273.    When fonts are enabled (see the .enable command) the font
  274. designations are replaced by the escape sequenced required for
  275. the printer defined in the Blackbeard font file. When the
  276. formatter starts up it looks for a font file. Blackbeard looks
  277. in the current subdirectory for a file named BB.FNT.  This file
  278. defines the font to escape sequence relationship.  If there is
  279. not a file named BB.CFG in the current subdirectory, Blackbeard
  280. will look in the DOS environment for the symbol BBFNT, if it is
  281. found it will use the filename supplied with the symbol.  This
  282. will let you keep one font file and use Blackbeard from any disk
  283. or directory.  To set BBFNT place this command or one similar in
  284. your autoexec.bat file
  285.  
  286.      SET BBFNT=C:\BB.FNT
  287.  
  288. The font file looks like the following:
  289.  
  290. 0  18             18       ( normal = 10 CPI)
  291. 1  27,45,1        27,45,0  ( underline)
  292. 2  27,69          27,70    ( bold )
  293. 3  27,69          27,70    ( italic)
  294. 4  27,69          27,70    ( subscript)
  295. 5  27,69          27,70    ( superscript)
  296. 6  15             18       ( compressed)
  297. 7  14             20       ( double)
  298. 8  27,58          27,58    ( 12 CPI)
  299.  
  300. The first number is the font number. The second set of numbers
  301. define the "ON" sequence for that font number. The third set of
  302. numbers define the "OFF" sequence for that font number. The
  303. rest of the line is ignored and can be used for comments.
  304. A comma separates numbers of a set. Spaces separates sets from sets.
  305.  
  306. To use a font enclose your text between font designators as
  307. follows:
  308.  
  309.       "127""1"abcdef"127""1"
  310.  
  311.    "127" and "1" stand for the ASCII characters 127 and 01.
  312. This can be done using the insert special character feature of
  313. Blackbeard. When this file is formatted, these font designators
  314. will be replaced so they will look like (using the sample font
  315. file):
  316.  
  317.       "27""45""1"abcdef"27""45""0"
  318.  
  319.    There are several font files included on your Blackbeard
  320. distribution diskette. The following is a descriptive list of
  321. these files.
  322.  
  323. Filename    Description
  324. ----------  ----------------------------------------------------
  325. TP351.FNT   Fonts for the TOSHIBA P351
  326. BB.FNT      The Blackbeard standard font file (≈ TP351.FNT)
  327. EMX80.FNT   Epson MX 80 font file
  328.  
  329.